From 4b83be0e26a221ca6fe6f3b720bcf033117823fb Mon Sep 17 00:00:00 2001
From: Benjamin Otte <otte@redhat.com>
Date: Wed, 13 Jun 2012 04:20:06 +0200
Subject: [PATCH] iconview: Add documentation abour different sizes

Did I mention I hate code that has different kinds of "boxes" or
coordinate systems but no clear way to distinguish them?
It's all ints here...

https://bugzilla.gnome.org/show_bug.cgi?id=677809
---
 gtk/gtkiconview.c | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 55c7d80575..df40fb6fe9 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -1393,6 +1393,31 @@ adjust_wrap_width (GtkIconView *icon_view)
     }
 }
 
+/* General notes about layout
+ *
+ * The icon view is layouted like this:
+ *
+ * +----------+  s  +----------+
+ * | padding  |  p  | padding  |
+ * | +------+ |  a  | +------+ |
+ * | | cell | |  c  | | cell | |
+ * | +------+ |  i  | +------+ |
+ * |          |  n  |          |
+ * +----------+  g  +----------+
+ *
+ * In size request and allocation code, there are 3 sizes that are used:
+ * * cell size
+ *   This is the size returned by gtk_cell_area_get_preferred_foo(). In places
+ *   where code is interacting with the cell area and renderers this is useful.
+ * * padded size
+ *   This is the cell size plus the item padding on each side.
+ * * spaced size
+ *   This is the padded size plus the spacing. This is what's used for most
+ *   calculations because it can (ab)use the following formula:
+ *   iconview_size = 2 * margin + n_items * spaced_size - spacing
+ * So when reading this code and fixing my bugs where I confuse these two, be
+ * aware of this distinction.
+ */
 static void
 cell_area_get_preferred_size (GtkIconView        *icon_view,
                               GtkCellAreaContext *context,
-- 
2.30.2